隨著模擬器功能越來越完善，從大肢體運動 到 Finger Tutting 微觀幾何，我們已經能創造成百上千種複雜的手勢與動作。

但隨之而來的，是實務操作上一個非常明顯的全新痛點：每次為了做出一組相同的「標準 90 度手盒」或「槍型手勢」，都必須重新微調幾十個關節角度。 當你要編排一套 8 拍甚至 16 拍的連招（Combo）時，這種重複校正極度消耗創作熱情。

為了徹底解決這個問題，今天 DAY 24 我們要在 3D Tutting 模擬器中建立完全模組化的 「手臂動作姿勢庫」 與 「掌指手勢庫」！

核心功能規格

我們將「身體肢體」與「掌指微觀」雙軌解耦，讓創作者能像疊積木一樣自由組合：

1.核心概念：關節分兩組，各管各的

• 動作姿勢庫：只讀寫「身體」關節——軀幹、手臂、腿、頭，完全不碰手指。
• 掌指手勢庫：只讀寫「手指」30個指節（雙手加起來），完全不碰身體。

2.資料怎麼存、怎麼套用?

儲存

• 姿勢庫：把當下 target 裡所有身體關節角度抓出來（四捨五入到小數點1位），包成一筆物件 {id, name, savedAt, data}存入陣列。
• 手勢庫：同樣邏輯，但只抓30個手指關節。

套用

點清單裡的項目，呼叫對應的 applyFn，把存好的角度一個個塞回 target
套用完會呼叫 pushHistory()，所以套用姿勢庫/手勢庫這個動作本身可以被 undo 復原（呼應剛才聊到的歷史堆疊機制）

3.整批匯出/匯入

• 整批匯出：把整個陣列包成一個 JSON 檔下載
• 整批匯入：讀進一個 JSON 陣列，過濾出格式正確的項目（要有 data 欄位），然後跳出確認框讓使用者選擇：
  • 「確定」＝合併進現有清單（items.concat(cleaned)）
  • 「取消」＝整批取代現有清單
• 單筆匯入：讀進單一物件，直接補一筆新的 id 加進清單（避免匯入的舊 id 跟本地衝突）

結語

兩個庫本質上是「同一套通用清單管理系統」的兩份實例，唯一差異是各自負責的關節子集合（身體 vs 手指），靠這樣的正交切分讓使用者能把姿態和手勢自由組合，並且共用同一套存檔／匯出入／UI 邏輯，降低維護成本。

現在創作者只需將常用的經典 Tutting 組合一次性儲存為預設集（Presets），未來編舞時就能像組裝積木一樣：軀幹選用「胸前平舉姿勢」，左手點擊套用「槍型」、右手點擊套用「直角」，瞬間完成複雜的幾何組合。

將「肢體空間」與「指尖微觀」解耦的架構，不僅提升了模擬器的編舞效率，更為後續實作動畫序列與預設招式庫打下了堅實的資料基礎！

動作姿勢庫與掌指手勢庫 — 功能規格 Prompt

# 動作姿勢庫與掌指手勢庫 — 功能規格 Prompt

以下是新增功能的完整需求規格，可作為 prompt 保存或用於其他專案複用。

## 背景

在既有的 3D Tutting 模擬器（Three.js + FK/IK 骨架系統）中，新增兩個獨立的自訂資料庫功能：**動作姿勢庫**與**掌指手勢庫**，並分別在分頁列新增對應分頁。

---

## 功能一：動作姿勢庫

- **儲存範圍**：身體關節（軀幹/脊椎/頭/肩/手臂/腿），不包含手指指節

- **功能需求**：
  1. 輸入名稱 → 儲存「目前身體姿勢」到清單
  2. 清單項目可一鍵套用（僅覆蓋身體關節，不影響手指目前狀態）
  3. 清單項目可刪除（刪除前需確認）
  4. 單筆匯出：把單一姿勢存成 JSON 檔下載
  5. 單筆匯入：讀取單一姿勢 JSON 檔，加入清單
  6. 全部匯出：把整個姿勢庫存成 JSON 陣列檔下載
  7. 全部匯入：讀取 JSON 陣列檔，匯入前詢問「合併現有清單」或「整批取代」
  8. 資料持久化：存在瀏覽器 localStorage，重新整理頁面後仍保留

---

## 功能二：掌指手勢庫

- **儲存範圍**：左右手全部指節角度（Mixamo 命名，5指 x 3節 x 左右手 = 30 個 key）

- **功能需求**：與動作姿勢庫完全相同（儲存/套用/刪除/單筆匯出入/全部匯出入/localStorage 持久化），但只讀寫手指資料，不碰身體關節

---

## 共同設計原則

- 兩個庫必須互相獨立：套用姿勢不影響目前手勢，套用手勢不影響目前姿勢，可自由混搭使用
- UI 風格需與既有分頁一致（沿用現有的 chip 清單樣式、按鈕樣式、深色主題配色）
- 匯入檔案格式錯誤時要有清楚的錯誤提示，不能讓程式崩潰或靜默失敗
- 核心邏輯（渲染清單、儲存、匯出、匯入）盡量共用同一套程式碼（用工廠函式或參數化設計），避免姿勢庫與手勢庫各寫一份重複邏輯
- 每個清單項目需保留：唯一 id、名稱、儲存時間戳記、關節角度資料
- 每個分頁需包含：
  - 名稱輸入框＋儲存按鈕
  - 匯出全部／匯入全部／匯入單一按鈕
  - 單筆匯出按鈕放在各清單項目旁
  - 清單容器（含空清單時的提示文字）

---

## 資料結構範例

**單一項目：**
``json
{
  "id": "唯一識別碼",
  "name": "姿勢/手勢名稱",
  "savedAt": 1234567890,
  "data": {
    "關節key": [x, y, z]
  }
}
``

**全部匯出檔案：** 上述項目物件組成的 JSON 陣列

**單筆匯出檔案：** 單一項目物件本身